Skip to main content

Retrieve Order Details

Retrieves the order details with order number or merchant order number.

API URL​

Request​

Http Header​

Attributes

  • Content-Language String

    • Language in which the response message will be used.
    • Currently, only English is supported.
    • Example value: en
    • Maximum length: 10

  • Content-Type String Required

    • Media type of the request body.
    • Required for operations with a request body.
    • Format: application/<format> (e.g., application/json)
    • Example value: application/json

  • sign String Required

    • Request signature using private-key cryptography.
    • Ensures the payment gateway can verify the request origin.

  • Partner-Id String Required

    • Merchant ID of your account.
    • Example value: 200001200101
    • Maximum length: 12

Http Body​

requestTime Timestamp Required

If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.

Example value: 1581493898000

bizContent Object

Use merchantOrderNo to specify an order.

  • merchantOrderNo String Required

    The merchant's reference number of a specific transfer order..

    Example value: Me23484

    Maximum length: 64

Request Sample​

// Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "RXF8WmC67QSnr62l3oU33fjpUvAo6Yrgvk05c/vYLtmHRGMoAH4qSnap2pto3mY7KgyP5wkNUsyQXJ/ZwbfccSONLb5zA7Z7q74IsOwdJw3BKXxVWr4tfjkA02Pfcp0cZWjE/Y8jTcbtgdc5VI90LNmkgPWbrSlDbNW8p3NlhnKg+Xfl95SgMBPF9afttsU/2a5jLnZXSVcXoSthxpJ6XkZwd45+jhOjBguT+IC8uLVSNRvwDisRGgf9PYv39OH6ITEhbY2sgjkdzBZBOZlt7awy2vkMEsePsuafwrNhuz7xzjj55PzNzk8+zCUu/791OhC/eFUyGimtDw5mX9cyQw=="
}

// Http Body
{
    "body": {
        "bizContent": {
            "merchantOrderNo": "M536433721888"
        },
        "requestTime": 1585142880000
    }
}

Response​

Http Header​

sign String Required

When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.

Http Body​

head

Attributes

  • applyStatus Enum Required

    • The result of the request. Possible values:
      • SUCCESS: Application successful.
      • FAIL: Application failed. Check the code and msg for the exact reason.
      • ERROR: Application error. Signature verification failed. Ensure the private key used for the signature and the public key uploaded on the PayBy portal are a valid key pair.

  • code String Required

    • Response code.
    • Example value: 0
    • Maximum length: 10

  • msg String

    • Description of the response code.
    • Maximum length: 200

  • traceCode String

    • Internal code for locating the error.

body

Notice

Body is returned only when applystatus = success, and code = 0. If applystatus = error or failed; or applystatus = success, code !=0 , that indicates an error. Please check errors and try again.

  • transferToBankOrder Object

    Attributes

    • requestTime Timestamp Required

      • Time the request was initiated.
      • Example value: 1581493898000

    • merchantOrderNo String Required

      • Unique identifier for the merchant's order.
      • Example value: S10000

    • orderNo String Required

      • Unique identifier for the PayBy transaction.
      • Example value: O1000

    • product String Required

      • Name of the product or service.
      • Example value: Transfer To Bank

    • status String Required

      • Current status of the order.
      • Example value: -

    • paymentInfo TransferToBankPaymentInfo

      • Detailed information about the payment processing, especially related to fees and timing.

      • Example value:

        {
          "arrivalTime": 1585133416000,
          "payerFeeAmount": {
            "amount": 0,
            "currency": "AED"
          }
        }

      • payerFeeAmount Money

        • The fee charged to the sender (payer), including amount and currency.
        • Example value: -

      • arrivalTime Timestamp (milliseconds, 3-digit precision)

        • Timestamp when the funds were expected to arrive or did arrive.
        • Example value: 1585133416000

    • amount Money Required

      • Transaction amount.
      • Example value: (empty)

    • holderName String Required

      • SHA-256 hash of the original name.
      • Example value: (empty)

    • Iban String Required

      • SHA-256 hash of the original IBAN.
      • Example value: (empty)

    • swiftCode String

      • SWIFT code of the beneficiary bank.
      • Example value: (empty)

    • memo String

      • Remarks or notes for the payment.
      • Example value: (empty)

    • notifyUrl String

      • URL for backend notifications.
      • Example value: (empty)

    • failDes String

      • Reason for order failure.
      • Example value: -

    • beneficiaryAddress String

      • SHA-256 hash of the original address.
      • Example value: (empty)

    • bankReference String

      • Reference number associated with the bank.
      • Example value: (empty)

    • fundoutAmount Money

      • Amount credited to the beneficiary.
      • Example value: (empty)

    • rate BigDecimal

      • Exchange rate used for the transaction.
      • Example value: (empty)

    • networkCode String Required

      • Financial network used.
      • Example value: LOCAL

    • countryCode String

      • Country code of the beneficiary bank.
      • Example value: -

    • bankName String

      • Name of the beneficiary bank.
      • Example value: -

    • fedwireCode String

      • Fedwire account code.
      • Example value: -

    • intermediaryBank String

      • SWIFT code of the intermediary bank.
      • Example value: -

    • branchName String

      • Name of the bank branch.
      • Example value: (empty)

    • beneficiaryType String Required

      • Type of beneficiary account.
      • Example value: IBAN

    • purposeCode String

      • Code indicating the purpose of the transaction.
      • Example value: COM

Response Sample​

// Http Header
{
    "sign": "VvlCywDHE0Pi35ypeJymje1GWHbDPhy3UJqPZTLnM0QqFa3QW+Yzc25kgsrB9t58c2oRdWo+stcvMhOeOgbrXNOhLAECD5bpSr2L1xEVhowd1k8tNlq+w2WhzUM0A77YVO2wapqqtBvsFi09o/ix7gCyX+850oLLxEEbbBR48fufVJxcOQ4y7bdkSufd+9gY4vdcJYMmnToSVQ72ObekhyZiXhT5zfnHjbFYGGpRXh/HvDiE+OGdTDYmHH4Ui+funH9kCg291/pWIV8Yp0hIQJ29cuJyCYsm1brkLopU1eak7fgculNo5SnCZH9nTIHYsIQtsMAXgI8q0MecBR2ovw=="
}

// Http Body
{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "1133"
    },
    "body": {
        "transferToBankOrder": {
            "amount": {
                "amount": 0.01,
                "currency": "AED"
            },
            "holderName": "00d74f270d2251e8fa6e7f3b1ea06bd3b5f32dfe4719f9df60982c55b24e4898",
            "iban": "1fc44f25c178c422f705054c669cfa6133f6dc8e1fe24b3d96f847667db8b92c",             
            "beneficiaryAddress": "ec36f7ed0f1095595da9a506c1cb352c9b89b69c4ceb2c562128c7241661afde",
            "memo": "Your memo",
            "merchantOrderNo": "M536433721888",
            "notifyUrl": "http://www.yoursite.com",
            "orderNo": "911585133415003759",
            "paymentInfo": {
                "arrivalTime": 1585133416000,
                "payerFeeAmount": {
                    "amount": 0,
                    "currency": "AED"
                }
            },
            "product": "Transfer To Bank",
            "requestTime": 1585133415287,
            "status": "SUCCESS",
            "swiftCode": "BBMEAEAD",
            "bankReference": "2000000111101"
        }
    }
}

Response Codes​

The following response codes are used for the status field:

CodeMessageCauseWorkaround
0SUCCESSSuccess
400INVALID_PARAMETERInvalid parametersAdjust the request parameters
400REQUESTTIME_TOO_EARLYRequest time is too far in the pastAdjust the request time
400REQUESTTIME_TOO_LATERRequest time is too far in the futureAdjust the request time
402RATE_LIMIT_REJECTToo many requests in a short periodReduce request frequency
403UNAUTHORIZEDAPI not authorizedContact PayBy
404SERVICE_NOT_AVAILABLEAPI service unavailableContact PayBy
500SYSTEM_ERRORSystem errorContact PayBy and retry later
504SERVICE_TIMEOUTService timeoutRetry later
601RISK_FAILRisk control validation failedAdjust the business logic
62004MERCHANT_ORDER_NO_NOT_EXISTThe order with the given merchant order number does not existCheck and correct the merchant order number